6. Components¶

This chapter describes for each component the interfaces that it MAY implement.

6.1. Enrollment Component¶

The enrollment component MAY implement the following interfaces:

6.1.1. Enrollment Services¶

This interface describes enrollment services in the context of an identity system. It is based on the following principles:

When enrollment is done in one step, the CreateEnrollment can contain all the data and an additional flag (finalize) to indicate all data was collected.
During the process, enrollment structure can be updated. Only the data that changed need to be transferred. Data not included is left unchanged on the server. In the following example, the biographic data is not changed.
Images can be passed by value or reference. When passed by value, they are base64-encoded.
Existing standards are used whenever possible, for instance preferred image format for biometric data is ISO-19794.

About documents

Adding one document or deleting one document implies that:

The full document list is read (ReadEnrollment)
The document list is altered locally to the enrollment client (add or delete)
The full document list is sent back using the UpdateEnrollment service

6.1.1.1. Services¶

createEnrollment(enrollmentID, enrollmentTypeId, enrollmentFlags, requestData, biometricData, biographicData, documentData, finalize, transactionID)

Insert a new enrollment.

Authorization: enroll.write

Parameters:

enrollmentID (str) – The ID of the enrollment. If the enrollment already exists for the ID an error is returned.
enrollmentTypeId (str) – The enrollment type ID of the enrollment.
enrollmentFlags (dict) – The enrollment custom flags.
requestData (dict) – The enrollment data related to the enrollment itself.
biometricData (list) – The enrollment biometric data.
biographicData (dict) – The enrollment biographic data.
documentData (list) – The enrollment biometric data.
finalize (str) – Flag to indicate that data was collected.
transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error and in case of success the enrollment ID.

readEnrollment(enrollmentID, attributes, transactionID)

Retrieve the attributes of an enrollment.

Authorization: enroll.read

Parameters:	enrollmentID (str) – The ID of the enrollment. attributes (set) – The (optional) set of required attributes to retrieve. transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error and in case of success the enrollment data.

updateEnrollment(enrollmentID, enrollmentTypeId, enrollmentFlags, requestData, biometricData, biographicData, documentData, finalize, transactionID)

Update an enrollment.

Authorization: enroll.write

Parameters:

enrollmentID (str) – The ID of the enrollment. If the enrollment already exists for the ID an error is returned.
enrollmentTypeId (str) – The enrollment type ID of the enrollment.
enrollmentFlags (dict) – The enrollment custom flags.
requestData (dict) – The enrollment data related to the enrollment itself.
biometricData (list) – The enrollment biometric data, this can be partial data.
biographicData (dict) – The enrollment biographic data.
documentData (list) – The enrollment biometric data, this can be partial data.
finalize (str) – Flag to indicate that data was collected.
transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error.

partialupdateEnrollment(enrollmentID, enrollmentTypeId, enrollmentFlags, requestData, biometricData, biographicData, documentData, finalize, transactionID)

Update part of an enrollment. Not all attributes are mandatory. The payload is defined as per RFC 7396.

Authorization: enroll.write

Parameters:

enrollmentID (str) – The ID of the enrollment. If the enrollment already exists for the ID an error is returned.
enrollmentTypeId (str) – The enrollment type ID of the enrollment.
enrollmentFlags (dict) – The enrollment custom flags.
requestData (dict) – The enrollment data related to the enrollment itself.
biometricData (list) – The enrollment biometric data, this can be partial data.
biographicData (dict) – The enrollment biographic data.
documentData (list) – The enrollment biometric data, this can be partial data.
finalize (str) – Flag to indicate that data was collected.
transactionID (string) – The client generated transactionID.

Returns:

a status indicating success or error.

finalizeEnrollment(enrollmentID, transactionID)

When all the enrollment steps are done, the enrollment client indicates to the enrollment server that all data has been collected and that any further processing can be triggered.

Authorization: enroll.write

Parameters:	enrollmentID (str) – The ID of the enrollment. transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error.

deleteEnrollment(enrollmentID, transactionID)

Deletes the enrollment

Authorization: enroll.write

Parameters:	enrollmentID (str) – The ID of the enrollment. transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error.

findEnrollments(expressions, transactionID)

Retrieve a list of enrollments which match passed in search criteria.

Authorization: enroll.read

Parameters:	expressions (list[(str,str,str)]) – The expressions to evaluate. Each expression is described with the attribute’s name, the operator (one of `<`, `>`, `=`, `>=`, `<=`) and the attribute value transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error and in case of success the matching enrollment list.

sendBuffer(enrollmentId, data)

This service is used to send separately the buffers of the images. Buffers can be sent any time from the enrollment client prior to the create or update.

Authorization: enroll.buf.write

Parameters:	enrollmentID (str) – The ID of the enrollment. data (image) – The image of the request. transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error and in case of success the buffer ID.

getBuffer(enrollmentId, bufferId)

This service is used to get images of buffers.

Authorization: enroll.buf.read

Parameters:	enrollmentID (str) – The ID of the enrollment. bufferID (str) – The ID of the buffer. transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error and in case of success the image of the buffer.

6.1.1.2. Attributes¶

The “attributes” parameter used in “read” calls is used to provide a set of identifiers that limit the amount of data that is returned. It is often the case that the whole data set is not required, but instead, a subset of that data. Where possible, existing standards based identifiers should be used for the attributes to retrieve.

E.g. For surname/familyname, use OID 2.5.4.4 or id-at-surname.

Some calls may require new attributes to be defined. E.g. when retrieving biometric data, the caller may only want the meta data about that biometric, rather than the actual biometric data.

6.1.1.3. Transaction ID¶

The transactionID is a string provided by the client application to identity the request being submitted. It can be used for tracing and debugging.

6.1.1.4. Data Model¶

Table 6.1 Enrolment Data Model¶
Type	Description	Example
Enrollment	Set of person data which are captured.	TBD
Document Data	The document data of the enrollment.	TBD
Biometric Data	Digital representation of biometric characteristics. All images can be passed by value (image buffer is in the request) or by reference (the address of the image is in the request). All images are compliant with ISO 19794. ISO 19794 allows multiple encoding and supports additional metadata specific to fingerprint, palmprint, portrait or iris.	fingerprint, portrait, iris
Biographic Data	a dictionary (list of names and values) giving the biographic data of interest for the biometric services.	TBD
Enrollment Flags	a dictionary (list of names and values) for custom flags.	TBD
Request Data	a dictionary (list of names and values) for data related to the enrollment itself (the operator, the station, the data, etc.).	TBD
Attributes	a dictionary (list of names and values or range of values) describing the attributes to return. Attributes can apply on biographic data, document data, request data, or enrollment flag data.	TBD
Expressions	Each expression is described with the attribute’s name, the operator (one of `<`, `>`, `=`, `>=`, `<=`, `!=`) and the attribute value	TBD

Fig. 6.1 Enrollment Data Model¶

6.2. Population Registry¶

The population registry component MAY implement the following interfaces:

6.2.1. Notification¶

See Notification for the technical details of this interface.

The subscription & notification process is managed by a middleware and is described in the following diagram:

Fig. 6.2 Subscription & Notification Process¶

6.2.1.1. Services¶

6.2.1.1.1. For the Subscriber¶

subscribe(topic, URL)

Subscribe a URL to receive notifications sent to one topic

Authorization: notif.sub.write

Parameters:	topic (str) – Topic URL (str) – URL to be called when a notification is available
Returns:	a subscription ID

This service is synchronous.

listSubscriptions()

Get all subscriptions

Authorization: notif.sub.read

Parameters:	URL (str) – URL to be called when a notification is available
Returns:	a subscription ID

This service is synchronous.

unsubscribe(id)

Unsubscribe a URL from the list of receiver for one topic

Authorization: notif.sub.write

Parameters:	id (str) – Subscription ID
Returns:	bool

This service is synchronous.

confirm(token)

Used to confirm that the URL used during the subscription is valid

Authorization: notif.sub.write

Parameters:	token (str) – A token send through the URL.
Returns:	bool

This service is synchronous.

6.2.1.1.2. For the Publisher¶

createTopic(topic)

Create a new topic. This is required before an event can be sent to it.

Authorization: notif.topic.write

Parameters:	topic (str) – Topic
Returns:	N/A

This service is synchronous.

listTopics()

Get the list of all existing topics.

Authorization: notif.topic.read

Returns:	N/A

This service is synchronous.

deleteTopic(topic)

Delete a topic.

Authorization: notif.topic.write

Parameters:	topic (str) – Topic
Returns:	N/A

This service is synchronous.

publish(topic, subject, message)

Notify of a new event all systems that subscribed to this topic

Authorization: notif.topic.publish

Parameters:	topic (str) – Topic subject (str) – The subject of the message message (str) – The message itself (a string buffer)
Returns:	N/A

This service is asynchronous (systems that subscribed on this topic are notified asynchronously).

6.2.1.2. Dictionaries¶

As an example, below there is a list of events that each component might handle.

Table 6.2 Event Type¶
Event Type	Emitted by CR	Emitted by PR
Live birth	✔
Death	✔
Fœtal Death	✔
Marriage	✔
Divorce	✔
Annulment	✔
Separation, judicial	✔
Adoption	✔
Legitimation	✔
Recognition	✔
Change of name	✔
Change of gender	✔
New person		✔
Duplicate person	✔	✔

6.2.2. Data Access¶

See Data Access for the technical details of this interface.

6.2.2.1. Services¶

readPersonAttributes(UIN, names)

Read person attributes.

Authorization: pr.person.read or cr.person.read

Parameters:	UIN (str) – The person’s UIN names (list[str]) – The names of the attributes requested
Returns:	a list of pair (name,value). In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

This service is synchronous. It can be used to retrieve attributes from CR or from PR.

Fig. 6.3 readPersonAttributes Sequence Diagram¶

matchPersonAttributes(UIN, attributes)

Match person attributes. This service is used to check the value of attributes without exposing private data. The implementation can use a simple comparison or a more advanced technique (for example: phonetic comparison for names)

Authorization: pr.person.match or cr.person.match

Parameters:	UIN (str) – The person’s UIN attributes (list[(str,str)]) – The attributes to match. Each attribute is described with its name and the expected value
Returns:	If all attributes match, a Yes is returned. If one attribute does not match, a No is returned along with a list of (name,reason) for each non-matching attribute.

This service is synchronous. It can be used to match attributes in CR or in PR.

Fig. 6.4 matchPersonAttributes Sequence Diagram¶

verifyPersonAttributes(UIN, expressions)

Evaluate expressions on person attributes. This service is used to evaluate simple expressions on person’s attributes without exposing private data The implementation can use a simple comparison or a more advanced technique (for example: phonetic comparison for names)

Authorization: pr.person.verify or cr.person.verify

Parameters:	UIN (str) – The person’s UIN expressions (list[(str,str,str)]) – The expressions to evaluate. Each expression is described with the attribute’s name, the operator (one of `<`, `>`, `=`, `>=`, `<=`) and the attribute value
Returns:	A Yes if all expressions are true, a No if one expression is false, a Unknown if To be defined

This service is synchronous. It can be used to verify attributes in CR or in PR.

Fig. 6.5 verifyPersonAttributes Sequence Diagram¶

queryPersonUIN(attributes)

Query the persons by a set of attributes. This service is used when the UIN is unknown. The implementation can use a simple comparison or a more advanced technique (for example: phonetic comparison for names)

Authorization: pr.person.read or cr.person.read

Parameters:	attributes (list[(str,str)]) – The attributes to be used to find UIN. Each attribute is described with its name and its value
Returns:	a list of matching UIN

This service is synchronous. It can be used to get the UIN of a person.

Fig. 6.6 queryPersonUIN Sequence Diagram¶

queryPersonList(attributes, names)

Query the persons by a list of attributes and their values. This service is proposed as an optimization of a sequence of calls to queryPersonUIN() and readPersonAttributes().

Authorization: pr.person.read or cr.person.read

Parameters:	attributes (list[(str,str)]) – The attributes to be used to find the persons. Each attribute is described with its name and its value names (list[str]) – The names of the attributes requested
Returns:	a list of lists of pairs (name,value). In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

This service is synchronous. It can be used to retrieve attributes from CR or from PR.

Fig. 6.7 queryPersonList Sequence Diagram¶

readDocument(UINs, documentType, format)

Read in a selected format (PDF, image, …) a document such as a marriage certificate.

Authorization: pr.document.read or cr.document.read

Parameters:	UIN (list[str]) – The list of UINs for the persons concerned by the document documentType (str) – The type of document (birth certificate, etc.) format (str) – The format of the returned/requested document
Returns:	The list of the requested documents

This service is synchronous. It can be used to get the documents for a person.

Fig. 6.8 readDocument Sequence Diagram¶

6.2.2.2. Dictionaries¶

As an example, below there is a list of attributes/documents that each component might handle.

Table 6.3 Person Attributes¶
Attribute Name	In CR	In PR	Description
UIN	✔	✔
first name	✔	✔
last name	✔	✔
spouse name	✔	✔
date of birth	✔	✔
place of birth	✔	✔
gender	✔	✔
date of death	✔	✔
place of death	✔
reason of death	✔
status		✔	Example: missing, wanted, dead, etc.

Table 6.4 Certificate Attributes¶
Attribute Name	In CR	In PR	Description
officer name	✔
number	✔
date	✔
place	✔
type	✔

Table 6.5 Union Attributes¶
Attribute Name	In CR	In PR	Description
date of union	✔
place of union	✔
conjoint1 UIN	✔
conjoint2 UIN	✔
date of divorce	✔

Table 6.6 Filiation Attributes¶
Attribute Name	In CR	In PR	Description
parent1 UIN	✔
parent2 UIN	✔

Table 6.7 Document Type¶
Document Type	Description
birth certificate	To be completed
death certificate	To be completed
marriage certificate	To be completed

6.2.3. Population Registry Services¶

This interface describes services to manage a registry of the population in the context of an identity system. It is based on the following principles:

It supports a history of identities, meaning that a person has one identity and this identity has a history.
Images can be passed by value or reference. When passed by value, they are base64-encoded.
Existing standards are used whenever possible.
This interface is complementary to the data access interface. The data access interface is used to query the persons and uses the reference identity to return attributes.
The population registry can store the biometric data or can rely on the ABIS subsystem to do it. The preferred solution, for a clean separation of data of different nature and by application of GDPR principles, is to put the biometric data only in the ABIS. Yet many existing systems store biometric data with the biographic data and this specification gives the flexibility to do it.

See Population Registry Management for the technical details of this interface.

6.2.3.1. Services¶

createPerson(personID, personData, transactionID)

Create a new person.

Authorization: pr.person.write

Parameters:	personID (str) – The ID of the person. If the person already exists for the ID an error is returned. personData – The person attributes. transactionID (str) – A free text used to track the system activities related to the same transaction.
Returns:	a status indicating success or error.

readPerson(personID, transactionID)

Read the attributes of a person.

Authorization: pr.person.read

Parameters:	personID (str) – The ID of the person. transactionID (str) – A free text used to track the system activities related to the same transaction.
Returns:	a status indicating success or error and in case of success the person data.

updatePerson(personID, personData, transactionID)

Update a person.

Authorization: pr.person.write

Parameters:	personID (str) – The ID of the person. personData (dict) – The person data.
Returns:	a status indicating success or error.

deletePerson(personID, transactionID)

Delete a person and all its identities.

Authorization: pr.person.write

Parameters:	personID (str) – The ID of the person. transactionID (str) – A free text used to track the system activities related to the same transaction.
Returns:	a status indicating success or error.

mergePerson(personID1, personID2, transactionID)

Merge two person records into a single one. Identity ID are preserved and in case of duplicates an error is returned and no changes are done. The reference identity is not changed.

Authorization: pr.person.write

Parameters:

personID1 (str) – The ID of the person that will receive new identities
personID2 (str) – The ID of the person that will give its identities. It will be deleted if the move of all identities is successful.
transactionID (str) – A free text used to track the system activities related to the same transaction.
options (dict) – the processing options. Supported options are priority.

Returns:

a status indicating success or error.

createIdentity(personID, identityID, identity, transactionID)

Create a new identity in a person. If no identityID is provided, a new one is generated. If identityID is provided, it is checked for uniqueness and used for the identity if unique. An error is returned if the provided identityID is not unique.

Authorization: pr.identity.write

Parameters:	personID (str) – The ID of the person. identityID (str) – The ID of the identity. identity – The new identity data. transactionID (str) – A free text used to track the system activities related to the same transaction.
Returns:	a status indicating success or error.

readIdentity(personID, identityID, transactionID)

Read one or all the identities of one person.

Authorization: pr.identity.read

Parameters:	personID (str) – The ID of the person. identityID (str) – The ID of the identity. If not provided, all identities are returned. transactionID (str) – A free text used to track the system activities related to the same transaction.
Returns:	a status indicating success or error, and in case of success a list of identities.

updateIdentity(personID, identityID, identity, transactionID)

Update an identity. An identity can be updated only in the status claimed.

Authorization: pr.identity.write

Parameters:	personID (str) – The ID of the person. identityID (str) – The ID of the identity. identity – The identity data. transactionID (str) – A free text used to track the system activities related to the same transaction.
Returns:	a status indicating success or error.

partialUpdateIdentity(personID, identityID, identity, transactionID)

Update part of an identity. Not all attributes are mandatory. The payload is defined as per RFC 7396. An identity can be updated only in the status claimed.

Authorization: pr.identity.write

Parameters:	personID (str) – The ID of the person. identityID (str) – The ID of the identity. identity – Part of the identity data.
Returns:	a status indicating success or error.

deleteIdentity(personID, identityID, transactionID)

Delete an identity.

Authorization: pr.identity.write

Parameters:	personID (str) – The ID of the person. identityID (str) – The ID of the identity. transactionID (str) – A free text used to track the system activities related to the same transaction.
Returns:	a status indicating success or error.

setIdentityStatus(personID, identityID, status, transactionID)

Set an identity status.

Authorization: pr.identity.write

Parameters:	personID (str) – The ID of the person. identityID (str) – The ID of the identity. status (str) – The new status of the identity. transactionID (str) – A free text used to track the system activities related to the same transaction.
Returns:	a status indicating success or error.

defineReference(personID, identityID, transactionID)

Define the reference identity of one person.

Authorization: pr.reference.write

Parameters:	personID (str) – The ID of the person. identityID (str) – The ID of the identity being now the reference. transactionID (str) – A free text used to track the system activities related to the same transaction.
Returns:	a status indicating success or error.

readReference(personID, transactionID)

Read the reference identity of one person.

Authorization: pr.reference.read

Parameters:	personID (str) – The ID of the person. transactionID (str) – A free text used to track the system activities related to the same transaction.
Returns:	a status indicating success or error and in case of success the reference identity.

readGalleries(transactionID)

Read the ID of all the galleries.

Authorization: pr.gallery.read

Parameters:	transactionID (str) – A free text used to track the system activities related to the same transaction.
Returns:	a status indicating success or error, and in case of success a list of gallery ID.

readGalleryContent(galleryID, transactionID)

Read the content of one gallery, i.e. the IDs of all the records linked to this gallery.

Authorization: pr.gallery.read

Parameters:	galleryID (str) – Gallery whose content will be returned. transactionID (str) – A free text used to track the system activities related to the same transaction.
Returns:	a status indicating success or error. In case of success a list of person/identity IDs.

6.2.3.2. Data Model¶

Table 6.8 Population Registry Data Model¶
Type	Description	Example
Gallery	A group of persons related by a common purpose, designation, or status. A person can belong to multiple galleries.	`VIP`, `Wanted`, etc.
Person	Person who is known to an identity assurance system. A person record has: a status, such as `active` or `inactive`, defining the status of the record (the record can be excluded from queries based on this status), a physical status, such as `alive` or `dead`, defining the status of the person, a set of identities, keeping track of all identity data submitted by the person during the life of the system, a reference identity, i.e. a consolidated view of all the identities defining the current correct identity of the person. It corresponds usually to the last valid identity but it can also include data from previous identities.	N/A
Identity	The attributes describing an identity of a person. An identity has a status such as: `claimed` (identity not yet validated), `valid` (the identity is valid), `invalid` (the identity is not valid), `revoked` (the identity cannot be used any longer). An identity can be updated only in the status `claimed`. The allowed transitions for the status are represented below: The attributes are separated into two categories: the biographic data and the contextual data.	N/A
Biographic Data	A dictionary (list of names and values) giving the biographic data of the identity	`firstName`, `lastName`, `dateOfBirth`, etc.
Contextual Data	A dictionary (list of names and values) attached to the context of establishing the identity	`operatorName`, `enrollmentDate`, etc.
Biometric Data	Digital representation of biometric characteristics. All images can be passed by value (image buffer is in the request) or by reference (the address of the image is in the request). All images are compliant with ISO 19794. ISO 19794 allows multiple encoding and supports additional metadata specific to fingerprint, palmprint, portrait or iris.	fingerprint, portrait, iris
Document	The document data (images) attached to the identity and used to validate it.	Birth certificate, invoice

Fig. 6.9 Population Registry Data Model¶

6.3. Civil Registry¶

The civil registry component MAY implement the following interfaces:

6.3.1. Notification¶

See Notification for the technical details of this interface.

The subscription & notification process is managed by a middleware and is described in the following diagram:

Fig. 6.10 Subscription & Notification Process¶

6.3.1.1. Services¶

6.3.1.1.1. For the Subscriber¶

subscribe(topic, URL)

Subscribe a URL to receive notifications sent to one topic

Authorization: notif.sub.write

Parameters:	topic (str) – Topic URL (str) – URL to be called when a notification is available
Returns:	a subscription ID

This service is synchronous.

listSubscriptions()

Get all subscriptions

Authorization: notif.sub.read

Parameters:	URL (str) – URL to be called when a notification is available
Returns:	a subscription ID

This service is synchronous.

unsubscribe(id)

Unsubscribe a URL from the list of receiver for one topic

Authorization: notif.sub.write

Parameters:	id (str) – Subscription ID
Returns:	bool

This service is synchronous.

confirm(token)

Used to confirm that the URL used during the subscription is valid

Authorization: notif.sub.write

Parameters:	token (str) – A token send through the URL.
Returns:	bool

This service is synchronous.

6.3.1.1.2. For the Publisher¶

createTopic(topic)

Create a new topic. This is required before an event can be sent to it.

Authorization: notif.topic.write

Parameters:	topic (str) – Topic
Returns:	N/A

This service is synchronous.

listTopics()

Get the list of all existing topics.

Authorization: notif.topic.read

Returns:	N/A

This service is synchronous.

deleteTopic(topic)

Delete a topic.

Authorization: notif.topic.write

Parameters:	topic (str) – Topic
Returns:	N/A

This service is synchronous.

publish(topic, subject, message)

Notify of a new event all systems that subscribed to this topic

Authorization: notif.topic.publish

Parameters:	topic (str) – Topic subject (str) – The subject of the message message (str) – The message itself (a string buffer)
Returns:	N/A

This service is asynchronous (systems that subscribed on this topic are notified asynchronously).

6.3.1.2. Dictionaries¶

As an example, below there is a list of events that each component might handle.

Table 6.9 Event Type¶
Event Type	Emitted by CR	Emitted by PR
Live birth	✔
Death	✔
Fœtal Death	✔
Marriage	✔
Divorce	✔
Annulment	✔
Separation, judicial	✔
Adoption	✔
Legitimation	✔
Recognition	✔
Change of name	✔
Change of gender	✔
New person		✔
Duplicate person	✔	✔

6.3.2. Data Access¶

See Data Access for the technical details of this interface.

6.3.2.1. Services¶

readPersonAttributes(UIN, names)

Read person attributes.

Authorization: pr.person.read or cr.person.read

Parameters:	UIN (str) – The person’s UIN names (list[str]) – The names of the attributes requested
Returns:	a list of pair (name,value). In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

This service is synchronous. It can be used to retrieve attributes from CR or from PR.

Fig. 6.11 readPersonAttributes Sequence Diagram¶

matchPersonAttributes(UIN, attributes)

Match person attributes. This service is used to check the value of attributes without exposing private data. The implementation can use a simple comparison or a more advanced technique (for example: phonetic comparison for names)

Authorization: pr.person.match or cr.person.match

Parameters:	UIN (str) – The person’s UIN attributes (list[(str,str)]) – The attributes to match. Each attribute is described with its name and the expected value
Returns:	If all attributes match, a Yes is returned. If one attribute does not match, a No is returned along with a list of (name,reason) for each non-matching attribute.

This service is synchronous. It can be used to match attributes in CR or in PR.

Fig. 6.12 matchPersonAttributes Sequence Diagram¶

verifyPersonAttributes(UIN, expressions)

Evaluate expressions on person attributes. This service is used to evaluate simple expressions on person’s attributes without exposing private data The implementation can use a simple comparison or a more advanced technique (for example: phonetic comparison for names)

Authorization: pr.person.verify or cr.person.verify

Parameters:	UIN (str) – The person’s UIN expressions (list[(str,str,str)]) – The expressions to evaluate. Each expression is described with the attribute’s name, the operator (one of `<`, `>`, `=`, `>=`, `<=`) and the attribute value
Returns:	A Yes if all expressions are true, a No if one expression is false, a Unknown if To be defined

This service is synchronous. It can be used to verify attributes in CR or in PR.

Fig. 6.13 verifyPersonAttributes Sequence Diagram¶

queryPersonUIN(attributes)

Query the persons by a set of attributes. This service is used when the UIN is unknown. The implementation can use a simple comparison or a more advanced technique (for example: phonetic comparison for names)

Authorization: pr.person.read or cr.person.read

Parameters:	attributes (list[(str,str)]) – The attributes to be used to find UIN. Each attribute is described with its name and its value
Returns:	a list of matching UIN

This service is synchronous. It can be used to get the UIN of a person.

Fig. 6.14 queryPersonUIN Sequence Diagram¶

queryPersonList(attributes, names)

Query the persons by a list of attributes and their values. This service is proposed as an optimization of a sequence of calls to queryPersonUIN() and readPersonAttributes().

Authorization: pr.person.read or cr.person.read

Parameters:	attributes (list[(str,str)]) – The attributes to be used to find the persons. Each attribute is described with its name and its value names (list[str]) – The names of the attributes requested
Returns:	a list of lists of pairs (name,value). In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

This service is synchronous. It can be used to retrieve attributes from CR or from PR.

Fig. 6.15 queryPersonList Sequence Diagram¶

readDocument(UINs, documentType, format)

Read in a selected format (PDF, image, …) a document such as a marriage certificate.

Authorization: pr.document.read or cr.document.read

Parameters:	UIN (list[str]) – The list of UINs for the persons concerned by the document documentType (str) – The type of document (birth certificate, etc.) format (str) – The format of the returned/requested document
Returns:	The list of the requested documents

This service is synchronous. It can be used to get the documents for a person.

Fig. 6.16 readDocument Sequence Diagram¶

6.3.2.2. Dictionaries¶

As an example, below there is a list of attributes/documents that each component might handle.

Table 6.10 Person Attributes¶
Attribute Name	In CR	In PR	Description
UIN	✔	✔
first name	✔	✔
last name	✔	✔
spouse name	✔	✔
date of birth	✔	✔
place of birth	✔	✔
gender	✔	✔
date of death	✔	✔
place of death	✔
reason of death	✔
status		✔	Example: missing, wanted, dead, etc.

Table 6.11 Certificate Attributes¶
Attribute Name	In CR	In PR	Description
officer name	✔
number	✔
date	✔
place	✔
type	✔

Table 6.12 Union Attributes¶
Attribute Name	In CR	In PR	Description
date of union	✔
place of union	✔
conjoint1 UIN	✔
conjoint2 UIN	✔
date of divorce	✔

Table 6.13 Filiation Attributes¶
Attribute Name	In CR	In PR	Description
parent1 UIN	✔
parent2 UIN	✔

Table 6.14 Document Type¶
Document Type	Description
birth certificate	To be completed
death certificate	To be completed
marriage certificate	To be completed

6.4. UIN Generator¶

The UIN generator component MAY implement the following interfaces:

6.4.1. UIN Management¶

See UIN Management for the technical details of this interface.

6.4.1.1. Services¶

generateUIN(attributes)

Generate a new UIN.

Authorization: uin.generate

Parameters:	attributes (list[(str,str)]) – A list of pair (attribute name, value) that can be used to allocate a new UIN
Returns:	a new UIN or an error if the generation is not possible

This service is synchronous.

Fig. 6.17 generateUIN Sequence Diagram¶

6.5. ABIS¶

The ABIS component MAY implement the following interfaces:

6.5.1. Biometrics¶

This interface describes biometric services in the context of an identity system. It is based on the following principles:

It supports only multi-encounter model, meaning that an identity can have multiple set of biometric data, one for each encounter.
It does not expose templates (only images) for CRUD services, with one exception to support the use case of credentials with biometrics.
Images can be passed by value or reference. When passed by value, they are base64-encoded.
Existing standards are used whenever possible, for instance preferred image format for biometric data is ISO-19794.

About synchronous and asynchronous processing

Some services can be very slow depending on the algorithm used, the system workload, etc. Services are described so that:

If possible, the answer is provided synchronously in the response of the service.
If not possible for some reason, a status PENDING is returned and the answer, when available, is pushed to a callback provided by the client.

If no callback is provided, this indicates that the client wants a synchronous answer, whatever the time it takes.

If a callback is provided, the server will decide if the processing is done synchronously or asynchronously.

See Biometrics for the technical details of this interface.

6.5.1.1. Services¶

createEncounter(personID, encounterID, galleryID, biographicData, contextualData, biometricData, clientData, callback, transactionID, options)

Create a new encounter. No identify is performed.

Authorization: abis.encounter.write

Parameters:

personID (str) – The person ID. This is optional and will be generated if not provided
encounterID (str) – The encounter ID. This is optional and will be generated if not provided
galleryID (list(str)) – the gallery ID to which this encounter belongs. A minimum of one gallery must be provided
biographicData (dict) – The biographic data (ex: name, date of birth, gender, etc.)
contextualData (dict) – The contextual data (ex: encounter date, location, etc.)
biometricData (list) – the biometric data (images)
clientData (bytes) – additional data not interpreted by the server but stored as is and returned when encounter data is requested.
callback – The address of a service to be called when the result is available.
transactionID (str) – A free text used to track the system activities related to the same transaction.
options (dict) – the processing options. Supported options are priority, algorithm.

Returns:

a status indicating success, error, or pending operation. In case of success, the person ID and the encounter ID are returned. In case of pending operation, the result will be sent later.

readEncounter(personID, encounterID, callback, transactionID, options)

Read the data of an encounter.

Authorization: abis.encounter.read

Parameters:

personID (str) – The person ID
encounterID (str) – The encounter ID. This is optional. If not provided, all the encounters of the person are returned.
callback – The address of a service to be called when the result is available.
transactionID (str) – A free text used to track the system activities related to the same transaction.
options (dict) – the processing options. Supported options are priority.

Returns:

a status indicating success, error, or pending operation. In case of success, the encounter data is returned. In case of pending operation, the result will be sent later.

updateEncounter(personID, encounterID, galleryID, biographicData, contextualData, biometricData, callback, transactionID, options)

Update an encounter.

Authorization: abis.encounter.write

Parameters:

personID (str) – The person ID
encounterID (str) – The encounter ID
galleryID (list(str)) – the gallery ID to which this encounter belongs. A minimum of one gallery must be provided
biographicData (dict) – The biographic data (ex: name, date of birth, gender, etc.)
contextualData (dict) – The contextual data (ex: encounter date, location, etc.)
biometricData (list) – the biometric data (images)
clientData (bytes) – additional data not interpreted by the server but stored as is and returned when encounter data is requested.
callback – The address of a service to be called when the result is available.
transactionID (str) – A free text used to track the system activities related to the same transaction.
options (dict) – the processing options. Supported options are priority, algorithm.

Returns:

a status indicating success, error, or pending operation. In case of success, the person ID and the encounter ID are returned. In case of pending operation, the result will be sent later.

deleteEncounter(personID, encounterID, callback, transactionID, options)

Delete an encounter.

Authorization: abis.encounter.write

Parameters:

personID (str) – The person ID
encounterID (str) – The encounter ID. This is optional. If not provided, all the encounters of the person are deleted.
callback – The address of a service to be called when the result is available.
transactionID (str) – A free text used to track the system activities related to the same transaction.
options (dict) – the processing options. Supported options are priority.

Returns:

a status indicating success, error, or pending operation. In case of pending operation, the operation status will be sent later.

mergeEncounter(personID1, personID2, callback, transactionID, options)

Merge two sets of encounters into a single set. Merging a set of N encounters with a set of M encounters will result in a single set of N+M encounters. Encounter ID are preserved and in case of duplicates an error is returned and no changes are done.

Authorization: abis.encounter.write

Parameters:

personID1 (str) – The ID of the person that will receive new encounters
personID2 (str) – The ID of the person that will give its encounters
callback – The address of a service to be called when the result is available.
transactionID (str) – A free text used to track the system activities related to the same transaction.
options (dict) – the processing options. Supported options are priority.

Returns:

a status indicating success, error, or pending operation. In case of pending operation, the result will be sent later.

readTemplate(personID, encounterID, biometricType, biometricSubType, templateFormat, qualityFormat, callback, transactionID, options)

Read the generated template.

Authorization: abis.encounter.read

Parameters:

personID (str) – The person ID
encounterID (str) – The encounter ID.
biometricType (str) – The type of biometrics to consider (optional)
biometricSubType (str) – The subtype of biometrics to consider (optional)
templateFormat (str) – the format of the template to return (optional)
qualityFormat (str) – the format of the quality to return (optional)
callback – The address of a service to be called when the result is available.
transactionID (str) – A free text used to track the system activities related to the same transaction.
options (dict) – the processing options. Supported options are priority.

Returns:

a status indicating success, error, or pending operation. In case of success, a list of template data is returned. In case of pending operation, the result will be sent later.

setEncounterStatus(personID, encounterID, status, transactionID)

Set an encounter status.

Authorization: abis.encounter.write

Parameters:	personID (str) – The ID of the person. encounterID (str) – The encounter ID. status (str) – The new status of the encounter. transactionID (str) – A free text used to track the system activities related to the same transaction.
Returns:	a status indicating success or error.

readGalleries(callback, transactionID, options)

Read the ID of all the galleries.

Authorization: abis.gallery.read

Parameters:	callback – The address of a service to be called when the result is available. transactionID (str) – A free text used to track the system activities related to the same transaction. options (dict) – the processing options. Supported options are `priority`.
Returns:	a status indicating success, error, or pending operation. A list of gallery ID is returned, either synchronously or using the callback.

readGalleryContent(galleryID, callback, transactionID, options)

Read the content of one gallery, i.e. the IDs of all the records linked to this gallery.

Authorization: abis.gallery.read

Parameters:	galleryID (str) – Gallery whose content will be returned. callback – The address of a service to be called when the result is available. transactionID (str) – A free text used to track the system activities related to the same transaction. options (dict) – the processing options. Supported options are `priority`.
Returns:	a status indicating success, error, or pending operation. A list of persons/encounters is returned, either synchronously or using the callback.

identify(galleryID, filter, biometricData, callback, transactionID, options)

Identify a person using biometrics data and filters on biographic or contextual data. This may include multiple operations, including manual operations.

Authorization: abis.identify

Parameters:

galleryID (str) – Search only in this gallery.
filter (dict) – The input data (filters and biometric data)
biometricData – the biometric data.
callback – The address of a service to be called when the result is available.
transactionID (str) – A free text used to track the system activities related to the same transaction.
options (dict) – the processing options. Supported options are priority, maxNbCand, threshold, accuracyLevel.

Returns:

a status indicating success, error, or pending operation. A list of candidates is returned, either synchronously or using the callback.

identify(galleryID, filter, personID, callback, transactionID, options)

Identify a person using biometrics data of a person existing in the system and filters on biographic or contextual data. This may include multiple operations, including manual operations.

Authorization: abis.verify

Parameters:

galleryID (str) – Search only in this gallery.
filter (dict) – The input data (filters and biometric data)
personID – the person ID
callback – The address of a service to be called when the result is available.
transactionID (str) – A free text used to track the system activities related to the same transaction.
options (dict) – the processing options. Supported options are priority, maxNbCand, threshold, accuracyLevel.

Returns:

a status indicating success, error, or pending operation. A list of candidates is returned, either synchronously or using the callback.

verify(galleryID, personID, biometricData, callback, transactionID, options)

Verify an identity using biometrics data.

Authorization: To be defined

Parameters:

galleryID (str) – Search only in this gallery. If the person does not belong to this gallery, an error is returned.
personID (str) – The person ID
biometricData – The biometric data
callback – The address of a service to be called when the result is available.
transactionID (str) – A free text used to track the system activities related to the same transaction.
options (dict) – the processing options. Supported options are priority, threshold, accuracyLevel.

Returns:

a status indicating success, error, or pending operation. A status (boolean) is returned, either synchronously or using the callback. Optionally, details about the matching result can be provided like the score per biometric and per encounter.

verify(biometricData1, biometricData2, callback, transactionID, options)

Verify that two sets of biometrics data correspond to the same person.

Authorization: To be defined

Parameters:

biometricData1 – The first set of biometric data
biometricData2 – The second set of biometric data
callback – The address of a service to be called when the result is available.
transactionID (str) – A free text used to track the system activities related to the same transaction.
options (dict) – the processing options. Supported options are priority, threshold, accuracyLevel.

Returns:

a status indicating success, error, or pending operation. A status (boolean) is returned, either synchronously or using the callback. Optionally, details about the matching result can be provided like the score per the biometric.

6.5.1.2. Options¶

Table 6.15 Biometric Services Options¶
Name	Description
`priority`	Priority of the request. Values range from 0 to 9
`maxNbCand`	The maximum number of candidates to return.
`threshold`	The threshold to apply on the score to filter the candidates during an identification, authentication or verification.
`algorithm`	Specify the type of algorithm to be used.
`accuracyLevel`	Specify the accuracy expected of the request. This is to support different use cases, when different behavior of the ABIS is expected (response time, accuracy, consolidation/fusion, etc.).

6.5.1.3. Data Model¶

Table 6.16 Biometric Data Model¶
Type	Description	Example
Gallery	A group of persons related by a common purpose, designation, or status. A person can belong to multiple galleries.	TBD
Person	Person who is known to an identity assurance system.	TBD
Encounter	Event in which the client application interacts with a person resulting in data being collected during or about the encounter. An encounter is characterized by an identifier and a type (also called purpose in some context). An encounter has a status indicating if this encounter is used in the biometric searches. Allowed values are `active` or `inactive`.	TBD
Biographic Data	a dictionary (list of names and values) giving the biographic data of interest for the biometric services.	TBD
Filters	a dictionary (list of names and values or range of values) describing the filters during a search. Filters can apply on biographic data, contextual data or encounter type.	TBD
Biometric Data	Digital representation of biometric characteristics. All images can be passed by value (image buffer is in the request) or by reference (the address of the image is in the request). All images are compliant with ISO 19794. ISO 19794 allows multiple encoding and supports additional metadata specific to fingerprint, palmprint, portrait or iris.	fingerprint, portrait, iris
Candidate	Information about a candidate found during an identification	TBD
CandidateScore	Detailed information about a candidate found during an identification. It includes the score for the biometrics used. It can also be extended with proprietary information to better describe the matching result (for instance: rotation needed to align the probe and the candidate)	TBD
Template	A computed buffer corresponding to a biometric and allowing the comparison of biometrics. A template has a format that can be a standard format or a vendor-specific format.	N/A

Fig. 6.18 Biometric Data Model¶

6.6. Credential Management System¶

The credential management system component MAY implement the following interfaces:

6.6.1. Credential Services¶

This interface describes services to manage credentials and credential requests in the context of an identity system.

6.6.1.1. Services¶

createCredentialRequest(personID, credentialProfileID, additionalData, transactionID)

Request issuance of a secure credential.

Authorization: cms.request.write

Parameters:	personID (str) – The ID of the person. credentialProfileID (str) – The ID of the credential profile to issue to the person. additionalData (dict) – Additional data relating to the requested credential profile, e.g. credential lifetime if overriding default, delivery addresses, etc. transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error. In the case of success, a credential request identifier.

readCredentialRequest(credentialRequestID, attributes, transactionID)

Retrieve the data/status of a credential request.

Authorization: cms.request.read

Parameters:	credentialRequestID (str) – The ID of the credential request. attributes (set) – The (optional) set of required attributes to retrieve. transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error, and in case of success the issuance data/status.

updateCredentialRequest(credentialRequestID, additionalData, transactionID)

Update the requested issuance of a secure credential.

Authorization: cms.request.write

Parameters:	credentialRequestID (str) – The ID of the credential request. transactionID (string) – The client generated transactionID. additionalData (dict) – Additional data relating to the requested credential profile, e.g. credential lifetime if overriding default, delivery addresses, etc.
Returns:	a status indicating success or error.

deleteCredentialRequest(credentialRequestID, transactionID)

Delete/cancel the requested issuance of a secure credential.

Authorization: cms.request.write

Parameters:	credentialRequestID (str) – The ID of the credential request. transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error.

findCredentials(expressions, transactionID)

Retrieve a list of credentials that match the passed in search criteria.

Authorization: cms.credential.read

Parameters:	expressions (list[(str,str,str)]) – The expressions to evaluate. Each expression is described with the attribute’s name, the operator (one of `<`, `>`, `=`, `>=`, `<=`) and the attribute value. transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error, in the case of success the list of matching credentials.

readCredential(credentialID, attributes, transactionID)

Retrieve the attributes/status of an issued credential. A wide range of information may be returned, dependant on the type of credential that was issued, smart card, mobile, passport, etc.

Authorization: cms.credential.read

Parameters:	credentialID (str) – The ID of the credential. attributes (set) – The (optional) set of required attributes to retrieve. transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error, in the case of success the requested data will be returned.

suspendCredential(credentialID, additionalData, transactionID)

Suspend an issued credential. For electronic credentials this will suspend any PKI certificates that are present.

Authorization: cms.credential.write

Parameters:	credentialID (str) – The ID of the credential. additionalData (dict) – Additional data relating to the request, e.g. reason for suspension. transactionID (string) – The (optional) client generated transactionID.
Returns:	a status indicating success or error.

unsuspendCredential(credentialID, additionalData, transactionID)

Unsuspend an issued credential. For electronic credentials this will unsuspend any PKI certificates that are present.

Authorization: cms.credential.write

Parameters:	credentialID (str) – The ID of the credential. additionalData (dict) – Additional data relating to the request, e.g. reason for unsuspension. transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error.

revokeCredential(credentialID, additionalData, transactionID)

Revoke an issued credential. For electronic credentials this will revoke any PKI certificates that are present.

Authorization: cms.credential.write

Parameters:	credentialID (str) – The ID of the credential. additionalData (dict) – Additional data relating to the request, e.g. reason for revocation. transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error.

findCredentialProfiles(expressions, transactionID)

Retrieve a list of credential profils that match the passed in search criteria

Authorization: cms.profile.read

Parameters:	expressions (list[(str,str,str)]) – The expressions to evaluate. Each expression is described with the attribute’s name, the operator (one of `<`, `>`, `=`, `>=`, `<=`, `!=`) and the attribute value transactionID (string) – The client generated transactionID.
Returns:	a status indicating success or error, and in case of success the matching credential profile list.

6.6.1.2. Attributes¶

The “attributes” parameter used in “read” calls is used to provide a set of identifiers that limit the amount of data that is returned. It is often the case that the whole data set is not required, but instead, a subset of that data. @@ -128,7 +128,7 @@ attributes to retrieve.

E.g. For surname/familyname, use OID 2.5.4.4 or id-at-surname.

Some calls may require new attributes to be defined. E.g. when retrieving biometric data, the caller may only want the meta data about that biometric, rather than the actual biometric data.

6.7. Third Party Services¶

The third party component MAY implement the following interfaces:

6.7.1. ID Usage¶

6.7.1.1. Services¶

verifyIdentity(UIN[, IDAttribute])

Verify Identity based on UIN and set of Identity Attributes (biometric data, credential, etc.)

Authorization: To be defined

Parameters:	UIN (str) – The person’s UIN IDAttribute (list[str]) – A list of list of pair (name,value) requested
Returns:	Y or N

In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

identify([inIDAttribute][, outIDAttribute])

Identify a person based on a set of Identity Attributes (biometric data, credential, etc.)

Authorization: To be defined

Parameters:	inIDAttribute (list[str]) – A list of list of pair (name,value) requested outIDAttribute (list[str]) – A list of list of attribute names requested
Returns:	Y or N

In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

readAttributes(UIN, names)

Read person attributes.

Authorization: To be defined

Parameters:	UIN (str) – The person’s UIN names (list[str]) – The names of the attributes requested
Returns:	a list of pair (name,value). In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

readAttributeSet(UIN, setName)

Read person attributes corresponding to a predefined set name.

Authorization: To be defined

Parameters:	UIN (str) – The person’s UIN setName (str) – The name of predefined attributes set name
Returns:	a list of pair (name,value). In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error